home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsISHistory.idl < prev    next >
Text File  |  2006-05-08  |  7KB  |  175 lines
  1. /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1999
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Radha Kulkarni (radha@netscape.com)
  24.  *
  25.  * Alternatively, the contents of this file may be used under the terms of
  26.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28.  * in which case the provisions of the GPL or the LGPL are applicable instead
  29.  * of those above. If you wish to allow use of your version of this file only
  30.  * under the terms of either the GPL or the LGPL, and not to allow others to
  31.  * use your version of this file under the terms of the MPL, indicate your
  32.  * decision by deleting the provisions above and replace them with the notice
  33.  * and other provisions required by the GPL or the LGPL. If you do not delete
  34.  * the provisions above, a recipient may use your version of this file under
  35.  * the terms of any one of the MPL, the GPL or the LGPL.
  36.  *
  37.  * ***** END LICENSE BLOCK ***** */
  38.  
  39. #include "nsISupports.idl"
  40.  
  41. interface nsIHistoryEntry;
  42. interface nsISHistoryListener;
  43. interface nsISimpleEnumerator;
  44. /**
  45.  * An interface to the primary properties of the Session History
  46.  * component. In an embedded browser environment, the nsIWebBrowser
  47.  * object creates an instance of session history for each open window.
  48.  * A handle to the session history object can be obtained from
  49.  * nsIWebNavigation. In a non-embedded situation, the  owner of the
  50.  * session history component must create a instance of it and set
  51.  * it in the nsIWebNavigation object.
  52.  * This interface is accessible from javascript. 
  53.  *
  54.  * @status FROZEN
  55.  */
  56.  
  57.  
  58. %{C++
  59. #define NS_SHISTORY_CID \
  60. {0x7294fe9c, 0x14d8, 0x11d5, {0x98, 0x82, 0x00, 0xC0, 0x4f, 0xa0, 0x2f, 0x40}}
  61.  
  62. #define NS_SHISTORY_CONTRACTID "@mozilla.org/browser/shistory;1"
  63. %}
  64.  
  65. [scriptable, uuid(7294FE9B-14D8-11D5-9882-00C04FA02F40)]
  66. interface nsISHistory: nsISupports
  67. {
  68.   /**
  69.    * A readonly property of the interface that returns 
  70.    * the number of toplevel documents currently available
  71.    * in session history.
  72.    */
  73.    readonly attribute long count;
  74.  
  75.   /**
  76.    * A readonly property of the interface that returns 
  77.    * the index of the current document in session history.
  78.    */
  79.    readonly attribute long index;
  80.  
  81.   /**
  82.    * A read/write property of the interface, used to Get/Set
  83.    * the maximum number of toplevel documents, session history 
  84.    * can hold for each instance. 
  85.    */
  86.    attribute long maxLength;
  87.  
  88.   /**
  89.    * Called to obtain handle to the history entry at a
  90.    * given index.
  91.    *
  92.    * @param index             The index value whose entry is requested.
  93.    * @param modifyIndex       A boolean flag that indicates if the current
  94.    *                          index of session history should be modified 
  95.    *                          to the parameter index.
  96.    *
  97.    * @return                  <code>NS_OK</code> history entry for 
  98.    *                          the index is obtained successfully.
  99.    *                          <code>NS_ERROR_FAILURE</code> Error in obtaining
  100.    *                          history entry for the given index.
  101.    */
  102.    nsIHistoryEntry getEntryAtIndex(in long index, in boolean modifyIndex);
  103.  
  104.  
  105.   /**
  106.    * Called to purge older documents from history.
  107.    * Documents can be removed from session history for various 
  108.    * reasons. For example to  control memory usage of the browser, to 
  109.    * prevent users from loading documents from history, to erase evidence of
  110.    * prior page loads etc...
  111.    *
  112.    * @param numEntries        The number of toplevel documents to be
  113.    *                          purged from history. During purge operation,
  114.    *                          the latest documents are maintained and older 
  115.    *                          'numEntries' documents are removed from history.
  116.    * @throws                  <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code> Purge was vetod.
  117.    * @throws                  <code>NS_ERROR_FAILURE</code> numEntries is
  118.    *                          invalid or out of bounds with the size of history.
  119.    *                          
  120.    */
  121.    void PurgeHistory(in long numEntries);
  122.  
  123.   /**
  124.    * Called to register a listener for the session history component.
  125.    * Listeners are notified when pages are loaded or purged from history.
  126.    * 
  127.    * @param aListener         Listener object to be notified for all
  128.    *                          page loads that initiate in session history.
  129.    *
  130.    * @note                    A listener object must implement 
  131.    *                          nsISHistoryListener and nsSupportsWeakReference
  132.    *
  133.    * @see nsISHistoryListener
  134.    * @see nsSupportsWeakReference
  135.    */
  136.    void addSHistoryListener(in nsISHistoryListener aListener);
  137.  
  138.   /**
  139.    * Called to remove a listener for the session history component.
  140.    * Listeners are notified when pages are loaded from history.
  141.    * 
  142.    * @param aListener         Listener object to be removed from 
  143.    *                          session history.
  144.    *
  145.    * @note                    A listener object must implement 
  146.    *                          nsISHistoryListener and nsSupportsWeakReference
  147.    * @see nsISHistoryListener
  148.    * @see nsSupportsWeakReference
  149.    */ 
  150.    void removeSHistoryListener(in nsISHistoryListener aListener);
  151.  
  152.   /**
  153.    * Called to obtain a enumerator for all the  documents stored in 
  154.    * session history. The enumerator object thus returned by this method
  155.    * can be traversed using nsISimpleEnumerator. 
  156.    *
  157.    * @note  To access individual history entries of the enumerator, perform the
  158.    *        following steps:
  159.    *        1) Call nsISHistory->GetSHistoryEnumerator() to obtain handle 
  160.    *           the nsISimpleEnumerator object.
  161.    *        2) Use nsISimpleEnumerator->GetNext() on the object returned
  162.    *           by step #1 to obtain handle to the next object in the list. 
  163.    *           The object returned by this step is of type nsISupports.
  164.    *        3) Perform a QueryInterface on the object returned by step #2 
  165.    *           to nsIHistoryEntry.
  166.    *        4) Use nsIHistoryEntry to access properties of each history entry. 
  167.    *
  168.    * @see nsISimpleEnumerator
  169.    * @see nsIHistoryEntry
  170.    * @see QueryInterface()
  171.    * @see do_QueryInterface()
  172.    */
  173.    readonly attribute nsISimpleEnumerator SHistoryEnumerator;
  174. };
  175.